---
id: tooltip
category: overlay
title: Tooltip
package: '@chakra-ui/tooltip'
description:
  A tooltip is a brief, informative message that appears when a user interacts
  with an element.
aria: https://www.w3.org/TR/wai-aria-practices/#tooltip
---

## Import

```js
import { Tooltip } from '@chakra-ui/react'
```

## Usage

If the `children` of Tooltip is a `string`, we wrap with in a `span` with
`tabIndex` set to `0`, to ensure it meets the accessibility requirements.

> Note 🚨: If the `Tooltip` is wrapping a functional component, ensure that the
> functional component accepts a `ref` using `forwardRef`.

### Using custom components

```jsx manual=true
const CustomCard = React.forwardRef(({ children, ...rest }, ref) => (
  <Box p='1'>
    <Tag ref={ref} {...rest}>
      {children}
    </Tag>
  </Box>
))

const CustomToolTip = () => (
  <Tooltip label='Hover me'>
    <CustomCard>Tag Here</CustomCard>
  </Tooltip>
)

render(<CustomToolTip />)
```

```jsx
<Tooltip label="Hey, I'm here!" aria-label='A tooltip'>
  Hover me
</Tooltip>
```

### With an icon

```jsx
<Tooltip label='Phone number' fontSize='md'>
  <PhoneIcon />
</Tooltip>
```

> Note 🚨: If you're wrapping an icon from `react-icons`, you need to also wrap
> the icon in a `span` element as
> [`react-icons` icons do not use `forwardRef`](https://github.com/react-icons/react-icons/issues/336).

### With arrow

```jsx
<Tooltip hasArrow label='Search places' bg='gray.300' color='black'>
  <SearchIcon />
</Tooltip>
```

### Tooltip with focusable content

If the children of the tooltip is a focusable element, the tooltip will show
when you focus or hover on the element, and will hide when you blur or move
cursor out of the element.

```jsx
<Tooltip hasArrow label='Search places' bg='red.600'>
  <Button>Button</Button>
</Tooltip>
```

### Disabling Tooltip

To disable showing a tooltip, pass the `isDisabled` prop to the `Tooltip`
component.

```jsx
<Tooltip isDisabled>
  <SearchIcon />
</Tooltip>
```

### Tooltip around disabled Button

By default the `Tooltip` is not shown when it is around a disabled `Button`.

```jsx
<Tooltip hasArrow label='You can not see me'>
  <Button isDisabled>Button</Button>
</Tooltip>
```

To show the `Tooltip` on a disabled `Button` you need to provide the
`shouldWrapChildren` prop. This means that the `Button` is surrounded by a span
on which the `Tooltip` is pinned. You could simply add a margin to the `Tooltip`
to have it more or less 'pinned' on the `Button` again.

```jsx
<Tooltip hasArrow label='You can see me' shouldWrapChildren mt='3'>
  <Button isDisabled>Button</Button>
</Tooltip>
```

> There's a case where the `borderRadius` of a button breaks when the button is
> in a `ButtonGroup` that has the `isAttached` prop set, and the tooltip has the
> `shouldWrapChildren` prop set. A workaround could be to pass the specific
> `borderRadius` depending on the `isDisabled` prop of the `Button`.

```jsx
<ButtonGroup colorScheme='teal' isAttached>
  <Tooltip label='works'>
    <Button>1</Button>
  </Tooltip>

  <Tooltip label='messes up border radius' shouldWrapChildren>
    <Button isDisabled>2</Button>
  </Tooltip>

  <Tooltip label='this could be a workaround' shouldWrapChildren>
    <Button isDisabled borderRadius='0'>
      3
    </Button>
  </Tooltip>

  <Button>4</Button>
</ButtonGroup>
```

## Placement

Using the `placement` prop you can adjust where your tooltip will be displayed.

```jsx
<VStack spacing={6}>
  <HStack spacing={6}>
    <Tooltip label='Auto start' placement='auto-start'>
      <Button>Auto-Start</Button>
    </Tooltip>

    <Tooltip label='Auto' placement='auto'>
      <Button>Auto</Button>
    </Tooltip>

    <Tooltip label='Auto end' placement='auto-end'>
      <Button>Auto-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip label='Top start' placement='top-start'>
      <Button>Top-Start</Button>
    </Tooltip>

    <Tooltip label='Top' placement='top'>
      <Button>Top</Button>
    </Tooltip>

    <Tooltip label='Top end' placement='top-end'>
      <Button>Top-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip label='Right start' placement='right-start'>
      <Button>Right-Start</Button>
    </Tooltip>

    <Tooltip label='Right' placement='right'>
      <Button>Right</Button>
    </Tooltip>

    <Tooltip label='Right end' placement='right-end'>
      <Button>Right-End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip label='Bottom start' placement='bottom-start'>
      <Button>Bottom Start</Button>
    </Tooltip>

    <Tooltip label='Bottom' placement='bottom'>
      <Button>Bottom</Button>
    </Tooltip>

    <Tooltip label='Bottom end' placement='bottom-end'>
      <Button>Bottom End</Button>
    </Tooltip>
  </HStack>

  <HStack spacing={6}>
    <Tooltip label='Left start' placement='left-start'>
      <Button>Left-Start</Button>
    </Tooltip>

    <Tooltip label='Left' placement='left'>
      <Button>Left</Button>
    </Tooltip>

    <Tooltip label='Left end' placement='left-end'>
      <Button>Left-End</Button>
    </Tooltip>
  </HStack>
</VStack>
```

## More examples

```jsx
<Wrap spacing={6}>
  <WrapItem>
    <Tooltip label='I close on click'>
      <Button>Close on Click - true(default)</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label="I don't close on click" closeOnClick={false}>
      <Button>Close on Click - false</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label='I am always open' placement='top' isOpen>
      <Button>Always Open</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label='I am open by default' placement='left' defaultIsOpen>
      <Button>Open on startup</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label='Opened after 500ms' openDelay={500}>
      <Button>Delay Open - 500ms</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label='Closed after 500ms' closeDelay={500}>
      <Button>Delay Close - 500ms</Button>
    </Tooltip>
  </WrapItem>

  <WrapItem>
    <Tooltip label='I have 15px arrow' hasArrow arrowSize={15}>
      <Button>Arrow size - 15px</Button>
    </Tooltip>
  </WrapItem>
</Wrap>
```
